---
slug: "api/content-pieces"
title: "Content Pieces"
---

**Content pieces** store all the content and related metadata that you create. With the API you can both retrieve and manage content pieces, including their variants and content groups they’re a part of.

Content of individual pieces is represented in a **JSON tree format**, described in detail in [a separate section](https://docs.vrite.io/api/content).

## Retrieve Content Piece

Retrieves details of the content piece specified by ID. You can specify additional options to retrieve specific _variant_ of the content piece, change return format of the _description_ and specify whether the _content_ should be included in the response.

<EndpointCard method="GET" endpoint="/content-pieces">
  <ResponseExample>
    ```json
    {
      "id": "cc6b3be85cb621fcca0568dd",
      "date": "string",
      "title": "string",
      "description": "string",
      "coverUrl": "string",
      "coverAlt": "string",
      "contentGroupId": "4a199daf7db303be195b8b86",
      "customData": "string",
      "canonicalLink": "string",
      "slug": "string",
      "filename": "string",
      "members": [
        {
          "id": "2d9eee214c97fe6849fab054",
          "profile": {
            "id": "fb4ccf50f9abc1699ef1ab13",
            "avatar": "string",
            "username": "string",
            "fullName": "string",
            "email": "user@example.com"
          }
        }
      ],
      "tags": [
        {
          "id": "330feb385dda6ed62c663771",
          "label": "string",
          "color": "gray"
        }
      ],
      "coverWidth": "string",
      "content": {
        ...
      }
    }
    ```
  </ResponseExample>
  
  <RequestExample label="JavaScript">
    ```javascript
    const client = createClient({
      token: "<API_TOKEN>",
    });
    const result = await client.contentPieces.get({
      id: "cc6b3be85cb621fcca0568dd",
      // Optional
      content: true,
      // Optional
      variant: "bf75ef612ccfdccb6e2d1fce",
      // Optional
      description: "text",
    });
    ```
  </RequestExample>
</EndpointCard>

## List Content Pieces

List content pieces assigned to the content group specified by ID. Supports pagination and filtering by slug or tag ID.

<EndpointCard
  method="GET"
  endpoint="/content-pieces/list"
>
  <ResponseExample>
    ```json
    [
      {
        "id": "db32b898d884369e2c1d5a8b",
        "date": "string",
        "title": "string",
        "description": "string",
        "coverUrl": "string",
        "coverAlt": "string",
        "contentGroupId": "283cb91a14c716723edeb5f8",
        "customData": "string",
        "canonicalLink": "string",
        "slug": "string",
        "filename": "string",
        "members": [
          {
            "id": "ce82b0a9173a1391c70a2b81",
            "profile": {
              "id": "6aa12008ec1c1478ca8233ae",
              "avatar": "string",
              "username": "string",
              "fullName": "string",
              "email": "user@example.com"
            }
          }
        ],
        "tags": [
          {
            "id": "48abb9ca53ee563e8ff35d31",
            "label": "string",
            "color": "gray"
          }
        ],
        "order": "string"
      }
    ]
    ```
  </ResponseExample>
  
  <RequestExample label="JavaScript">
    ```javascript
    const client = createClient({
      token: "<API_TOKEN>",
    });
    const result = await client.contentPieces.list({
      contentGroupId: "283cb91a14c716723edeb5f8",
      // Optional
      tagId: "48abb9ca53ee563e8ff35d31",
      // Optional
      slug: "blog/post",
      // Optional
      variant: "bf75ef612ccfdccb6e2d1fce",
      // Optional
      page: 1,
      // Optional
      perPage: 20,
    });
    ```
  </RequestExample>
</EndpointCard>

## Create Content Piece

Creates a content piece from the provided data and assigns it to the specified content group.

<EndpointCard method="POST" endpoint="/content-pieces">
  <ResponseExample>
    ```json
    {
      "id": "743b0098a83ee6ee0980736d"
    }
    ```
  </ResponseExample>
  
  <RequestExample label="JavaScript">
    ```javascript
    const client = createClient({
      token: "<API_TOKEN>",
    });
    const result = await client.contentPieces.create({
      title: "string",
      tags: ["513e845e5e6d9e92ba71fc82"],
      members: ["f1fd9a8268efd4d673ae04cc"],
      slug: "string",
      contentGroupId: "6c7ea0927b79efa9bb616820",
      // Optional
      date: "2025-02-23T14:34:14.099Z",
      // Optional
      description: "string",
      // Optional
      coverUrl: "string",
      // Optional
      coverAlt: "string",
      // Optional
      customData: "string",
      // Optional
      canonicalLink: "string",
      // Optional
      filename: "string",
      // Optional
      content: "string",
      // Optional
      referenceId: "7ee53ccbbb26195d90838cc1",
    });
    ```
  </RequestExample>
</EndpointCard>

## Update Content Piece

Updates a content piece (or specified variant) matched by ID, using the provided data. If a new content group is specified the piece will be reassigned to it.

<EndpointCard method="PUT" endpoint="/content-pieces">
  <RequestExample label="JavaScript">
    ```javascript
    const client = createClient({
      token: "<API_TOKEN>",
    });
    await client.contentPieces.update({
      id: "2279e093a802d7167be0de",
      // Optional
      variant: "bf75ef612ccfdccb6e2d1fce",
      // Optional
      date: "2025-02-23T14:34:14.099Z",
      // Optional
      title: "string",
      // Optional
      description: "string",
      // Optional
      tags: ["be431a7d817127f4afd71d23"],
      // Optional
      coverUrl: "string",
      // Optional
      coverAlt: "string",
      // Optional
      contentGroupId: "279d80fcf27e88aecb5ca4fc",
      // Optional
      customData: "string",
      // Optional
      canonicalLink: "string",
      // Optional
      slug: "string",
      // Optional
      filename: "string",
      // Optional
      members: ["06d82fd3fc8c4642f2b85fd0"],
      // Optional
      coverWidth: "string",
      // Optional
      content: "<p></p>",
    });
    ```
  </RequestExample>
</EndpointCard>

## Delete Content Piece

Deletes the content piece specified by ID, together with all its variants.

<EndpointCard method="DELETE" endpoint="/content-pieces">
  <RequestExample label="JavaScript">
    ```javascript
    const client = createClient({
      token: "<API_TOKEN>",
    });
    await client.contentPieces.delete({
      id: "2279e093a802d7167be0de",
    });
    ```
  </RequestExample>
</EndpointCard>
